Pular para o conteúdo principal

Utilizando no seu assistente local

Conexão local​

Antes de realizar a conexão local, é necessário possuir um aplicativo já criado e aprovado na área de desenvolvedor. Verifique Criação de aplicativo para mais informações.

A conexão local é direta: O assistente ou client configurado envia o seu token parametrizado a cada chamada, e o servidor apenas lê esse token. Não há sessão nem negociação, tudo o que o servidor precisa é de um token válido. Por isso o setup se resume a três coisas:

  • Um token;
  • Um arquivo de configuração;
  • Uma variável de ambiente que guarda o token.

Pré-requisitos​

  • Um assistente ou client compatível com o protocolo MCP instalado.
  • Um token do BTG Id válido (veja o passo 1 abaixo).

1. Obter um token do BTG Id​

A autenticação é feita pelo BTG Id. O token obrigatoriamente deve ser obtido via Authorization Code Flow — é o único fluxo que emite um token com consentimento delegado do usuário final, necessário para que o servidor MCP opere em nome de uma empresa. Fluxos sem consentimento do usuário (como Client Credentials) não são aceitos.

Realize o fluxo de Authorization Code e guarde o access token resultante — é ele que o Claude Code vai enviar.

O token identifica a empresa que você vai operar (a partir do consentimento dado no login).

Trate o token como uma senha

O token dá acesso às operações bancárias que ele autoriza. Não o cole em arquivos versionados, não o compartilhe e não o cole no chat do assistente. No passo a seguir ele deve ficar em uma variável de ambiente, nunca dentro do arquivo de configuração.

2. Configurar o arquivo de conexão​

Configurar ~/seu-repositório/.mcp.json

{
"mcpServers": {
  "btg-empresas-mcp": {
    "type": "http",
    "url": "https://mcp.empresas.btgpactual.com/mcp",
    "headers": {
      "Authorization": "Bearer ${BTG_MCP_TOKEN}"
    }
  }
}
}

3. Exportar o token​

Exporte o token antes inicializar sua ferramenta, usando o mesmo nome de variável que você referenciou no arquivo de configuração:

export BTG_MCP_TOKEN="<seu-token>"

4. Inicializar a ferramenta e conectar​

No diretório que contém o seu arquivo, inicialize sua ferramenta:

claude

A ferramenta lê o arquivo de configuração, resolve a variável de ambiente e conecta ao servidor. As ferramentas do BTG Empresas passam a ficar disponíveis na sessão.

5. Validar com uma consulta​

Peça, em linguagem natural, uma operação de leitura. Ela não exige confirmação e prova que a conexão está de pé:

O assistente escolhe a consulta adequada, executa contra o servidor do BTG Empresas e devolve o resultado.

Operações de escrita exigem confirmação​

Operações que movem dinheiro, como um PIX, um pagamento ou a emissão de um boleto, nunca são executadas sem confirmação. O assistente apresenta um resumo da operação (empresa, valor, favorecido e data, com o documento mascarado) e só prossegue após a sua aprovação explícita na conversa.

cuidado

A emissão de pagamento segue o fluxo padrão onde existe a necessidade de confirmação no aplicativo mobile do BTG Empresas ou no Internet Banking

Veja Segurança e boas práticas para entender por que esse passo existe e por que ele não deve ser dispensado.

Quando o token expira​

O token do BTG Id é de curta duração. Quando ele expira, as chamadas deixam de ser autorizadas. Gere um novo token, atualize a variável de ambiente e reinicie o Claude Code para que ele releia o valor:

export BTG_MCP_TOKEN="<novo-token>"